home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / music / deliay01.lha / dev / dev.doc
Text File  |  1994-10-18  |  10KB  |  247 lines
  1.  
  2. Intro
  3. =====
  4.  
  5. In this directory is located all the developers stuff. As you have probably
  6. already realized, DeliAY can play several AY formats, using proper AY
  7. Player. So, if you have written some ingenious tunes using your own
  8. replayer routine, why not to give it a try and rewrite the player for
  9. MC68000? Or perhaps send me the tunes and the Z80 source and let me see
  10. what can be done?
  11.  
  12. If you decide to write your own AY Player, please check the Amadeus.S and
  13. include40/misc/AYPlayer.i for more info about the DeliAY<->AYPlayer
  14. interface. Also, before starting your work I strongly recommend to contact
  15. me and to get the most recent info about this problematic available.
  16.  
  17. Contents
  18. ========
  19.  
  20. src/include40/misc/AYPlayer.i
  21.  
  22.                 Main includes, defines how each AY Player and AY Module has to
  23.                 look like
  24.  
  25. src/include40/misc/mine.i
  26.  
  27.                 Just few asm support macros
  28.  
  29. src/Amadeus.S
  30.  
  31.                 This is the source of the ZXAYAMAD. This is the example, how
  32.                 your own MC68000 rewrites could look like.
  33.  
  34. src/ZXAYEMUL.S
  35.  
  36.                 This is the source of a very special AY Player, which runs
  37.                 original Z80 code. Just for your information.
  38.  
  39. src/emultest.s
  40.  
  41.                 Source of emul.test.
  42.  
  43. src/AYdebugger.S
  44.  
  45.                 Source of the AYdebugger. You can see how to write modules
  46.                 with internal players (for special cases like this one there is
  47.                 no need to have one special player and one special init module)
  48.  
  49. tests/AYdebugger
  50.  
  51.                 You can use this special standalone module to play with the AY
  52.                 emulator. Just load it as any other module to DT2.
  53.  
  54. tests/emul.test
  55.  
  56.                 Load it to DT2 to see that ZXAYEMUL debug routine really works.
  57.  
  58. dev.doc
  59.  
  60.                 Obviously this file.
  61.  
  62.  
  63. Converting
  64. ==========
  65.  
  66. So,  let's assume that you have some marvellous tunes and want to listen to
  67. them on your Amiga. What are your choices?
  68.  
  69. 1) If you have several tunes, which you have written by yourself, using
  70. some widespread music program, you have to check out if there is not
  71. already some special player for that musical program. If not, or if you
  72. have used your own player which were never distributed to the public, you
  73. might decide to write your own AY Player. To do that, read AYPlayer.i to
  74. see how every AY player interfaces with PlayAY. Also, you can check the
  75. Amadeus.S how such player really looks like. Also note, that in addition to
  76. standard AYMOD header, you will have to specify your own SONG header
  77. structure... Also, you can read Amadeus.S how this might look like.
  78.  
  79. 2) If you have ripped some tune, and you are sure that the same player is
  80. not used with any other tune, it is üprobably not worth to rewrite it to
  81. MC68000. In that case, you might want to use the special Emul Player, which
  82. will emulate the original z80 replay routine with no need to rewrite it.
  83. Typical Emul module looks like this:
  84.  
  85.                 incdir  'Include40/'
  86.                 include misc/AYPlayer.i
  87.                 incdir  ''
  88. b
  89.                 AYMODHEADER     EMUL
  90.                 dc.w    0               ;no internal player
  91.                 dc.w    creator-*
  92.                 dc.w    misc-*
  93.                 dc.b    3-1             ;how many songs
  94.                 dc.b    0               ;which should start first
  95.                 dc.w    songdata-*
  96.  
  97. songdata        dc.w    name1-* ;use same name for all three songs.
  98.                 dc.w    data1-*
  99.                 dc.w    name1-*
  100.                 dc.w    data2-*
  101.                 dc.w    name1-*
  102.                 dc.w    data3-*
  103.  
  104. name1           dc.b    'Venom strikes back',0
  105. creator         dc.b    'Ben Daglish',0
  106. misc            dc.b    'Venom strikes back, (C) 19?? ????',0
  107.                 even
  108.                 
  109. data1           dc.b    0,1,2,3         ;channel assignement
  110.                 dc.w    3*60*50         ;songlen
  111.                 dc.w    50              ;fadelen
  112.                 dc.w    0<<8            ;init number to A
  113.                 dc.w    launch-*        ;launch structure
  114.                 dc.w    block-*         ;block list
  115. data2           dc.b    0,1,2,3
  116.                 dc.w    9*50
  117.                 dc.w    1
  118.                 dc.w    1<<8
  119.                 dc.w    launch-*
  120.                 dc.w    block-*
  121. data3           dc.b    0,1,2,3
  122.                 dc.w    3*50
  123.                 dc.w    1
  124.                 dc.w    2<<8
  125.                 dc.w    launch-*
  126.                 dc.w    block-*
  127.                 
  128. block           dc.w    49152           ;put code at address
  129.                 dc.w    e-code          ;len
  130.                 dc.w    code-*          ;take code from
  131. launch          dc.w    0               ;stack / use as EMUL_Block list terminator
  132.                 dc.w    0               ;init same as first block address
  133.                 dc.w    49155           ;interrupt
  134. code            incbin  'asm:sources/fxs/other/venom.data'
  135. e
  136.  
  137. For more info about how such module should look, read beginning of
  138. ZXAYEMUL.S. 
  139.  
  140. Few more words about emulation
  141. ==============================
  142.  
  143. It uses cut down version of my emulator I wrote some years ago. All
  144. instructions are emulated, except those RES C,3,(IX+1) and similar (I was
  145. just lazy, no other reason for this). All other like those with IY and IX
  146. halfs + SLIA (AKA SLL) are implemented.
  147.  
  148. For every song you specify what stack, init number, INIT routine and
  149. INTERRUPT routine emulator should use.
  150.  
  151. Init number is loaded to all registers (BC,DE,HL,BC',DE',HL',IX,IY + A and
  152. A' which contain MSB) and stack obviously to SP.
  153.  
  154. All ROM is filled with 255 (because of that popular $FFFF IM 2 trick), all
  155. RAM with 0. At address 0 this code is installed and executed.
  156.  
  157.                 call    INIT            ;whatever you passed in ems_init (or emd_address)
  158.                 ld      hl,INTERRUPT    ;from ems_interrupt
  159.                 ld      a,h             ;if no interrupt specified, we use the
  160.                 or      l               ;im2 interrupt table to find it out
  161.                 jr      nz,ok
  162.                 ld      a,i
  163.                 ld      h,a
  164.                 dec     l
  165.                 ld      e,(hl)
  166.                 inc     hl
  167.                 ld      d,(hl)
  168.                 ex      de,hl
  169. ok              ld      (here+1),hl
  170. loop            halt
  171. here            call    ????
  172.                 jr      loop
  173.                 ret                     ;this can be used as dummy init routine
  174.  
  175. Note that although address 0 contains $cd, address 65535+1 contains 243
  176. (little emulator magic:-), so you can use that popular IM 2 setting which
  177. jumps to 65535 executing JR 65524 there...
  178.  
  179. I didn't want to run the emulator from interrupts, IMHO it is too
  180. dangerous, if the z80 code hangs. Also, too much serial transfer errors
  181. usually occurs. So the solution is now like this:
  182.  
  183. Separate process is executed at priority 127. It runs the code described
  184. above. Halt is implemented as waiting for an external signal. Meanwhile,
  185. every interrupt EmulPlayer sends AY registers to the PlayAY, then sends
  186. signal to the emulator process. So the process does not block any
  187. interrupts even if it uses 100% of the CPU time.
  188.  
  189. So as you can see, no real interrupts are generated by the emulator, thus
  190. playing with DI/EI and IM x has no effect.
  191.  
  192. While playing already checked tunes this is not that important, but once
  193. you start converting your own tunes, this may become more important:
  194. imagine you execute some code which hangs the z80 (eg. jr $-2). It is not
  195. that bad since we are not hanged as interrupt, but as normal task. Problem
  196. is that the task has priority 127 and it takes all the time, so we can't
  197. stop it from other tasks with lower priority. Solution is simple:
  198. ZXAYEMUL reads the binary environment variable z80debug and sets the
  199. priority according to it. So before testing your own songs, you might want
  200. to type 'setenv z80debug °' or something like that. The song will sound
  201. terrible whenever you do some other activity (move a window or like), but
  202. it will never hang your computer :-)
  203.  
  204. Other problem is what should the emulator do if it runs some invalid
  205. instruction code. Solution: emulator process dumps all z80 registers and
  206. some internal to the ram:z80debug and disappears. However, the RAM still
  207. remains allocated until you drop the module, so you can simply see what
  208. happened. To see how the debug routine works, try playing emul.test.
  209.  
  210. Emulation - advantages vs disadvantages
  211. =======================================
  212.  
  213. Well, I realize that most people are simply too lazy to write their own AY
  214. Player, especially when I have released the ZXAYEMUL, which makes
  215. everything SOOOooo simple. However, they should realize following:
  216.  
  217. - Emulation is more CPU intensive. One should save his and others' time
  218.   and write MC68000 player.
  219. - Emulation consumes much more memory - 64KB for RAM and about 21K for the
  220.   emulator plus one more process and stack.
  221. - Frequencies are not fine tuned - simply ayfreq*8 is used. MC68000 players
  222.   use special pre-calculated table, so their output is more precise.
  223. - Storing z80 code and data for every tune takes much more space than just
  224.   storing the data, which is done for MC68000 players.
  225.  
  226. So, the following should be taken as general rule:
  227.  
  228. Use ZXAYEMUL only for your "quickhacks" (when you plan to rewrite the
  229. routine later to MC) to hear it. Also, use it, if there is only really few
  230. tunes using this player (few means aprox. less than 5).
  231.  
  232. In all other cases you should decide to write MC68000 player.
  233.  
  234. Never use ZXAYEMUL for collections which have about 20 modules or more and
  235. NEVER for musical programs. In such cases, MC68000 player should be ALWAYS
  236. written.
  237.  
  238.  
  239.  
  240. OK, that's it. If you miss some information here, please refer to includes
  241. and sources first, then try e-mailing me if you do not succeed.
  242.  
  243. Also, please send me all new tunes and new players. Thank You.
  244.  
  245. Patrik
  246.  
  247.